Release 10.1A: OpenEdge Development:
Progress Dynamics Basic Development

Retrieving and formatting error messages with aferrortxt.i

The include file you use in a validation procedure of any kind to format a message to prepare it for return to the client is aferrortxt.i. This include file has been designed to simplify and standardize the format of Progress Dynamics messages. The include file supports the unnamed arguments listed in Table 10–1.

Table 10–1: Supported arguments 

Argument	Description	Example
{1}	The Progress Dynamics Message Group.	AF,or ?, if using a hard-coded message.
{2}	The Progress Dynamics Message Code.	1 or a hard-coded message text.
{3}	The table name with which the message is associated.	Customer.
{4}	The field name with which the message is associated.	CustomerName.
{5 - 13}	Extra insertion arguments for the message (a maximum of nine are supported).	–

Resulting message format

The whole purpose of aferrortxt.i is to shield you from being concerned about the exact format of the various components of a formatted message. For informational purposes, this section explains the resulting format.

The include file equates to a single string value of the formatted message with appropriate delimiters. The format conforms to that expected and used by ADM2, which is:

message + CHR(4) + field + CHR(4) + table

Additionally, the format adds on the following for extra information on where the error occurred:

+ CHR(4) + PROGRAM-NAME(1) + CHR(4) + PROGRAM-NAME(2)

The format of the message part conforms to that required by Progress Dynamics for reading of the error message from a message table in the database, which is:

"group^code^program-name(1):program-name(2)^insert1|insert2|insert3|etc."

This is a carat (^)-separated list starting with the message group, then the message code, then the program the message occurred in, then a pipe (|)-delimited list of optional insertion codes to replace in the found message text returned from the database table.

Where insertion codes exist in the message text, values must be passed into the appropriate include file argument as explained above. Note that arguments to the include file must be passed in as unquoted variable names or single-quoted literals (for example, 'text'). If a literal contains spaces, then it must be enclosed in double quotes, then single quotes (for example, “'text space'”). If double quotes are specified, these will be dropped automatically. If arguments need to be left blank, then a placeholder of '?' must be used if the argument is not the last item in the list. Only the first two arguments are mandatory.

An example of an include file for a standard Progress Dynamics message with no insertion codes is:

{aferrortxt.i 'AF' '1'}

If the message to be displayed is not in the message table but simply hard-coded in the application procedure, then as noted in the argument description, the first argument is replaced by a question mark to signal this, and the second argument is the message text. An example use of an include file for a hard-coded message with no insertion codes is:

{aferrortxt.i '?' "'message text'"}

This example shows a Progress Dynamics message with two insertion codes and the table/field names specified:

{aferrortxt.i 'AF' '1' 'gsm_user' 'user_login_name' 'insert1’ ‘insert2’}

This example uses a Progress Dynamics message with two insertion codes and no table/field specified:

{aferrortxt.i 'AF' '1' '?' '?' 'insert1' 'insert2'}

Since aferrortxt.i actually evaluates to the formatted message, you must place it into a context where that message will be returned appropriately. An example in an application is:

IF <condition> THEN RETURN ERROR {aferrortxt.i 'AF' '1'}.

Or, as used in the procedures that come out of the Object Generator (and as you should normally also code such procedures), potentially multiple messages are accumulated in a single string using this convention:

cMessageList = cMessageList + (IF NUM-ENTRIES(cMessageList,CHR(3)) > 0 THEN CHR(3) ELSE '':U) + {aferrortxt.i 'AF' '8' 'Employee' '' "'EmpNum, '" cValueList }.

You should take advantage of the message table wherever possible in your application. Using standard messages for errors and for any other message displays supports the translation and reuse of messages. Hard-coding a message in an application means that it cannot easily be translated. Any change to the message text requires a change to the source code of the application.

The insertion codes can be a valuable mechanism for enabling you to reuse essentially the same message in different circumstances. Do not overdo the substitutions, however. If what you are inserting is the name of a table, field, or value, or some other entity that does not require translation, then message reuse is maximized. However, if you put text that really requires translation into the insertion parameter, such as “Error - &1”, then you would be defeating the purpose of the message table, which is to put the meaningful text in one place where it can be maintained, customized where necessary, and translated.